---
title: "NetSuite Authentication Setup for Unified"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/netsuite_authentication_setup_for unified-icon.svg
date: 2026-02-12T19:38:00.000Z
tag: Guides
description: "Unified supports two authentication methods for connecting to NetSuite,"
url: "https://docs.unified.to/guides/netsuite_authentication_setup_for unified"
---

# NetSuite Authentication Setup for Unified
------
_February 12, 2026_

Unified supports **two** authentication methods for connecting to NetSuite:

1. **OAuth 2.0 (Authorization Code Grant)** — browser-based login. **Recommended for most customers.** No need to copy/paste secrets. Tokens refresh automatically.
2. **Token-Based Authentication (TBA / OAuth 1.0a)** — you generate and paste 5 long-lived credentials. Best for server-to-server use cases, headless integrations, or where browser SSO isn't feasible.

Both methods talk to the same **SuiteTalk REST Web Services** API, so the underlying NetSuite feature flags and the role permissions list below are nearly identical. The main difference is **how Unified obtains the access token**.


**"Realm" = NetSuite Account ID** in every NetSuite client library and connector. We use the terms interchangeably below.


---


## **Which method should I choose?**


|                             | OAuth 2.0                                     | Token-Based Authentication (TBA)                                    |
| --------------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
| Setup effort                | Low — sign in once via NetSuite               | Higher — create Integration Record + Access Token                   |
| Credentials Unified stores  | access_token + refresh_token (auto-refreshed) | 5 long-lived secrets                                                |
| Best for                    | Most customers                                | Server-to-server, no human login, strict secret-management policies |
| Token lifespan              | Access token refreshes automatically          | Tokens are long-lived; rotate manually                              |
| What you provide to Unified | NetSuite Account ID + browser login           | Realm + Consumer Key/Secret + Token ID/Secret                       |
If you're not sure, **start with OAuth 2.0**.


---


## **What you need before starting (both methods)**

- Admin access in NetSuite (recommended), **OR** a NetSuite admin available to enable features and grant role permissions.
- The role used for the connection must have the correct permissions (see Required Role Permissions below).
- For sandbox testing, know whether you are in **Sandbox** vs **Production** — your Account ID and credentials are different between environments.

---


## **Step 1 — Enable the required NetSuite features (both methods)**


In NetSuite: **Setup → Company → Enable Features → SuiteCloud** tab.


Under **Manage Authentication**, enable:

- ✅ **OAuth 2.0** _(required for OAuth 2.0 method)_
- ✅ **Token-Based Authentication** _(required for TBA method)_

Under **SuiteTalk (Web Services)**, enable:

- ✅ **REST Web Services**

Without **REST Web Services**, all API calls return **401** regardless of which auth method you use, so make sure this is on.


Click **Save**.


---


## **Step 2 — Find your Realm / Account ID (both methods)**


Your **Realm** is your **NetSuite Account ID**.


**Option A — from the URL (fastest):**


When logged into NetSuite, the Account ID is in the host portion of the URL.


**Option B — from Company Information:**


**Setup → Company → Company Information** → look for **Account ID**.


**Sandbox note:** Sandbox accounts include a suffix like _SB1 (or -SB1 in URLs). Use **underscores** when entering the Account ID into Unified (e.g. 1234567_SB1). Unified normalizes between the URL form (-sb1) and the OAuth realm form (_SB1) automatically.


---


## **Step 3 — Configure the Role used for the connection (both methods)**


This is the **most important step** for avoiding 401 INVALID_LOGIN and "permission denied" errors. The role you use determines what Unified can read and write — for both OAuth 2.0 and TBA.


**Recommended: use the Administrator role**


The simplest and most reliable option:

- Use the **Administrator** role for the connecting user (OAuth 2.0), or for the token (TBA).

This guarantees:

- All record types are accessible
- All subsidiaries are accessible
- No hidden permission failures
- Fastest setup

**Optional: create a dedicated "Unified API" custom role**


If your security policy requires a least-privilege role, create one and grant the permissions in Required Role Permissions.


User-level restrictions can override role-level permissions. If you use a custom role, make sure the **user account itself** also has these permissions where applicable.


---


## **Step 4A — Connect using OAuth 2.0 (recommended)**


If you chose OAuth 2.0, you do **not** need to create an Integration Record or Access Token manually — Unified is already a pre-registered NetSuite OAuth 2.0 application.


**4A.1 Make sure your user has the right role**


The user who clicks "Connect" in Unified must have a role assigned that:

- Has the permissions listed in Required Role Permissions, **including** Log in using OAuth 2.0 Access Tokens.
- Has access to all subsidiaries you want Unified to sync.

Confirm role assignment under **Lists → Employees → Employees → [user] → Access** tab.


**4A.2 Connect from Unified**

1. In Unified, choose **NetSuite** as the integration.
2. Select **OAuth 2.0** as the authentication method (if asked).
3. Enter your **NetSuite Account ID** (e.g. 1234567 for production or 1234567_SB1 for sandbox).
4. You'll be redirected to NetSuite to sign in.
5. After signing in, NetSuite will show a consent screen with the requested scope (REST Web Services).
6. Choose the **Role** to authorize Unified under — this should be **Administrator** or the custom **Unified API** role.
7. Click **Allow**.

Unified will store the resulting access_token and refresh_token. The access token is automatically refreshed on expiry — you do not need to do anything further.


**4A.3 (Optional) Bring-Your-Own OAuth 2.0 credentials**


If your security policy requires you to use your **own** OAuth 2.0 Integration Record (rather than Unified's pre-registered one):

1. **Setup → Integration → Manage Integrations → New**
2. Name: e.g. "Unified Integration"
3. State: **Enabled**
4. On the **Authentication** tab:
- ✅ **OAuth 2.0**
- **Scope**: REST Web Services
- **Redirect URI**: provide the redirect URL given to you by Unified support
1. **Save** — NetSuite will display the **Client ID** and **Client Secret**. Copy them immediately (the secret cannot be retrieved later).
2. Share the Client ID / Client Secret with Unified support so we can install them on your workspace.

Reference: NetSuite OAuth 2.0 Authorization Code Grant Flow.


---


## **Step 4B — Connect using Token-Based Authentication (TBA)**


If you chose TBA, you'll provide Unified **5 values**:

- realm (NetSuite Account ID)
- consumer_key
- consumer_secret
- token_id (a.k.a. Token Key)
- token_secret

**4B.1 Create the Integration Record (Consumer Key / Secret)**

1. **Setup → Integration → Manage Integrations → New**
2. Name: e.g. "Unified Integration"
3. State: **Enabled**
4. On the **Authentication** tab:
- ✅ **Token-Based Authentication**
- (Leave OAuth 2.0 off unless you also plan to use OAuth 2.0 with the same record.)
1. **Save** — NetSuite displays the **Consumer Key** and **Consumer Secret**. **Copy them immediately**; the Consumer Secret cannot be viewed again.

These are the consumer_key and consumer_secret you'll give Unified.


**4B.2 Assign the role to the user who will own the token**


Tokens are created for a **User + Role + Integration Record** combination.

1. **Lists → Employees → Employees**
2. Select the user (or create a dedicated "API User" like unified-api@yourcompany.com)
3. Open the **Access** tab
4. Assign **Administrator** (recommended) **OR** your custom **Unified API** role
5. **Save**

**4B.3 Create the Access Token (Token ID / Token Secret)**

1. **Setup → Users/Roles → Access Tokens → New** _(may be labelled "Manage Access Tokens" in some UIs)_
2. Fill in:
- **Application Name**: the Integration Record you created (e.g. "Unified Integration")
- **User**: the user from 4B.2
- **Role**: **Administrator** (recommended) **OR** your **Unified API** role
- **Token Name**: optional but recommended (e.g. "Unified Production Token")
1. **Save** — NetSuite displays the **Token ID** and **Token Secret**. **Copy them immediately**.

The role you select here is the role whose permissions are enforced on **every** API call made with this token. Choosing the wrong role is the #1 cause of 401 INVALID_LOGIN and permission errors.


**4B.4 Provide the 5 values to Unified**


In the Unified connection form, enter:


| Unified field              | NetSuite value |
| -------------------------- | -------------- |
| realm_id (or "Account ID") | from Step 2    |
| consumer_key               | from Step 4B.1 |
| consumer_secret            | from Step 4B.1 |
| token_id                   | from Step 4B.3 |
| token_secret               | from Step 4B.3 |
---


## **Required Role Permissions**


These apply to **both** OAuth 2.0 and TBA when you choose a custom (non-Administrator) role. The list is the full set required for full accounting + CRM + commerce + HRIS support. You can trim it based on which Unified object types you actually use.


User-level restrictions can override role-level permissions. Make sure the user has these permissions in addition to the role.


**Transactions**


| Permission               | Level |
| ------------------------ | ----- |
| Access Payment Audit Log | Full  |
| Bill Purchase Orders     | Full  |
| Bills                    | Full  |
| Cash Sale                | Full  |
| Cash Sale Refund         | Full  |
| Credit Memo              | Full  |
| Cross Charge Journal     | View  |
| Customer Deposit         | Full  |
| Customer Payment         | Full  |
| Customer Refund          | Full  |
| Enter Vendor Credits     | Full  |
| Find Transaction         | Full  |
| Intercompany Adjustments | Full  |
| Invoice                  | Full  |
| Invoice Approval         | Full  |
| Invoice Sales Orders     | Full  |
| Item Receipt             | Full  |
| Item Shipment            | Full  |
| Journal Approval         | Full  |
| Make Journal Entry       | Full  |
| Opportunity              | Full  |
| Paycheck Journal         | Full  |
| Receive Order            | Full  |
| System Journal           | Full  |
**Reports**


| Permission         | Level |
| ------------------ | ----- |
| Transaction Detail | View  |
**Lists**


| Permission                      | Level |
| ------------------------------- | ----- |
| Accounts                        | Full  |
| Address List in Search          | Full  |
| Contact-Subsidiary Relationship | View  |
| Contacts                        | Full  |
| Currency                        | Full  |
| Customers                       | Full  |
| Employee Record                 | Full  |
| Employees                       | Full  |
| Inventory Cost Template         | View  |
| Locations                       | Full  |
| Partners                        | Full  |
| Perform Search                  | View  |
| Subsidiaries                    | Full  |
| Vendors                         | Full  |
**Setup**


| Permission                                   | Level                   |
| -------------------------------------------- | ----------------------- |
| Access Token Management                      | Full _(TBA only)_       |
| Integration Application                      | Full                    |
| Log in using Access Tokens                   | Full _(TBA only)_       |
| Log in using OAuth 2.0 Access Tokens         | Full _(OAuth 2.0 only)_ |
| OAuth 2.0 Authorized Applications Management | Full _(OAuth 2.0 only)_ |
| REST Web Services                            | Full                    |
| Two-Factor Authentication Base               | Full                    |
| User Access Tokens                           | Full _(TBA only)_       |
**Notes:**

- For TBA, the token inherits the permissions of the **role selected when the token is created** — not the user's default role.
- For OAuth 2.0, the access token inherits the permissions of the **role selected during the NetSuite consent screen**.
- Subsidiary access is controlled by role restrictions. If you use OneWorld, ensure the role has access to every subsidiary Unified must sync.

---


## **Validation & Troubleshooting**


**401 INVALID_LOGIN**


This almost always means one of:

- **Wrong role selected** when the OAuth 2.0 consent was approved, or when the TBA token was created.
- **Missing permissions** on the role:
- OAuth 2.0: missing Log in using OAuth 2.0 Access Tokens and/or OAuth 2.0 Authorized Applications Management
- TBA: missing Log in using Access Tokens, Access Token Management, or User Access Tokens
- **Wrong Account ID** (especially mixing sandbox with production).
- **REST Web Services** not enabled at the account level.
- **Integration Record disabled** (TBA only).
- **Consumer key/secret paired with a token from a different Integration Record** (TBA only).

The fastest way to diagnose is the **Login Audit Trail**:


**Setup → Users/Roles → User Management → View Login Audit Trail**


Filter by **Token-based** or **OAuth 2.0** logins and look at the failure reason on the most recent attempt.


**400 Bad Request / INSUFFICIENT_PERMISSION**


The connection authenticated but the role lacks permission for the specific record type Unified is trying to access. Add the missing permission from the Required Role Permissions table (most commonly **Lists → Subsidiaries**, **Lists → Accounts**, or a Transaction permission).


**Sandbox vs Production**

- Sandbox tokens / OAuth 2.0 consents only work against the sandbox account.
- Sandbox URLs use -sb1 (e.g. 1234567-sb1.app.netsuite.com); the realm sent on API calls uses _SB1 (e.g. 1234567_SB1). Unified handles the conversion automatically — just enter the Account ID with the _SB1 underscore form when prompted.

**Token rotation (TBA)**


NetSuite TBA tokens don't expire by default, but your security policy may require rotation:

1. Create a new Access Token under the same User + Role + Integration Record.
2. Update the token_id and token_secret in Unified.
3. Revoke the old token in **Setup → Users/Roles → Access Tokens**.

**Re-authorizing OAuth 2.0**


If a user is removed or their role changes, the OAuth 2.0 grant may become invalid. To re-authorize:

1. In NetSuite: **Setup → Users/Roles → OAuth 2.0 Authorized Applications** → revoke the existing Unified grant (optional but recommended).
2. In Unified, reconnect the NetSuite integration. You'll be sent back through the NetSuite consent screen.